perm filename LECT4.TEX[ARK,TEX] blob sn#766830 filedate 1984-08-20 generic text, type C, neo UTF8
COMMENT āŠ—   VALID 00006 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	% copyright 1984 by Arthur Keller ... All rights reserved
C00004 00003	\section{Input File for the Sample Business Letter}
C00011 00004	\section{The Letterformat Macros}
C00024 00005	\section{More About Macros}
C00029 00006	\section*{Assignment}
C00031 ENDMK
CāŠ—;
% copyright 1984 by Arthur Keller ... All rights reserved
\chapter{Sample application: a letter}

%Mon, August 20
%
%3-4pm
%Sample application: a letter
%>Using macros
%>Simple adaptations to existing macros
%
%4-6pm
%<lab assignment 2>

The purpose of this lecture is to learn how to modify an existing set of
macros to make it work for you.
To do this, we will look at a set of macros which define a business letter
on Stanford letterhead (which are in the file {\tt letterformat.tex}), at
the input file for a sample letter which makes use of those macros (stored
as {\tt sampleletter.tex}), and at the output which resulted.
The letterhead macros are based on those in Appendix~E of the \TeX book,
and have been adapted to create letterhead appropriate to a Stanford
University department.

One of the important messages of this lecture is that it isn't necessary
to completely understand a set of macros which someone else has written in
order to be able to customize it, that is, to adapt it to what you want the
output to look like.
In fact, we will see that it is quite easy to change the sample letterhead
into letterhead which you can use (at least if you happen to work for
Stanford).

\section{Input File for the Sample Business Letter}

We will first consider the input file for the sample letter. 
The first line, \cmd{input letterformat}, tells \TeX\ to read in the file
{\tt letterformat.tex} before it does anything else.  
A file which is input this way can contain macros, text to be typeset, or
some combination of the two.  In our example, the file {\tt letterformat.tex}
contains only macros.

Under the TOPS-20
operating system, \TeX\ will look for this file first on the connected
directory, then on the directory to which the logical name {\tt texinputs:}
has been assigned.  \TeX\ will assume that the filename has the extension
{\tt .tex} unless the extension is otherwise specified.

The next line in the input file, \cmd{nofatsletterhead}, tells \TeX\ to
execute a macro which was defined in the file {\tt letterhead.tex}.  This 
macro, which we'll look at shortly, is what creates the letterhead with
the Stanford name and seal, the sender's name, department, and phone, and
the date.
\footnote{Since
this is Stanford, the sample letter we'll look at---as well as the one in
the \TeX book---are full of anagrams on the word ``Stanford''.
``R. J. Drofnats'' is ``Stanford, Jr.'' spelled
backwards, and ``Dr.~No Fats'' is another anagram.}

The third line, \cmd{address}, executes another macro from the {\tt 
letterformat} file; it tells \TeX\ to begin the inside address of
the letter by placing each line in the input file on a separate
line of the output file (rather than creating justified and filled output).
This is accomplished with the command \cmd{obeylines} in one of the macros.

Notice that the input file uses tildes (\Tilde) between the addressee's title
and initials, as well as between ``St.'' and ``Anford''. \TeX\ was obviously not
going to put line breaks within the lines of the address, since they're so
short; this is an example of the tilde serving another function.  \TeX\ normally
assumes that a period following a lower-case letter signifies the end of a
sentence, and inserts extra space.  Using a tilde tells \TeX\ not to insert
extra space at the end of an abbreviation.  The \cmd{ } after the abbreviation
``Dept.'' serves the same function; remember, however, that \cmd{ } allows
\TeX\ to break the line at that point whereas a \Tilde\ does not.

If \TeX\ sees a period following an upper-case letter, it will assume that
the letter is an abbreviation and {\sl not} insert extra space after it. 
Thus there was no need to use tildes to obtain the acronym ``F.T.U.G.''.
\footnote{``Farm Ecology'' is an obvious pun on ``Pharmacology''.
The number ``1009'' is an obscure reference to the book {\sl Fundamental
Algorithms of Computer Programming} by Donald Knuth, the inventor of
\TeX, which the instructor will explain in class.  And ``F.T.U.G.'' is
an abbreviation, of course, for ``Fellow of the \TeX\ User's Group.''} 
However, suppose we have a sentence which ends with an upper-case letter,
for example, the sentence ``I sent my research proposal to ARPA{}.''
Here we do want \TeX\ to put extra space after a period following an 
upper-case letter, so we have to type {\tt \dots\ to ARPA\lb\rb .}
By doing this, \TeX\ will read the brackets after the final ``A'' in
``ARPA'', and do nothing with them; however, by the time it comes to the 
period it will have forgotten all about the upper-case letter and end
the sentence normally, with extra space after the period.


Continuing with the input file,
\cmd{body} is a macro which tells \TeX\ that what follows is the body
of the letter, to be set as normal text.  After the text of the letter
comes the command \cmd{closing}, which puts the closing (``Sincerely,'')
and the sender's name and title in the correct place with enough space
for the signature.  The last lines of input which pertain to the letter
itself are \cmd{annotations}, which again tells \TeX\ to \cmd{obeylines},
and the annotations which follow (the ``author's'' initials, followed
by the typists').  The final commands tell \TeX\ to finish the letter
off, print  mailing labels with the addressee's and return addresses,
and then stop.

\section{The Letterformat Macros}

Now let's take a closer look at the macros in the file 
\cmd{letterformat.tex}.  The first few lines (after the initial line of 
comments) define the macro \cmd{today}, which later is used to print 
the date on the letter.  A simple macro without parameters, which this
is, is defined by typing \cmd{def\bs macroname \lb definition\rb}, where
the {\tt definition} consists of some combination of control sequences
and text.

\begin{figure}[p]
\vskip6truein
\caption{Put sampleletter.tex here}
\end{figure}

\begin{figure}[p]
\vskip6truein
\caption{Put letterformat.tex page 1 here}
\end{figure}

\begin{figure}[p]
\vskip6truein
\caption{Put letterformat.tex page 2 here}
\end{figure}

The purpose of the \cmd{today} macro is to take three numerical values,
which \TeX\ stores under the labels ``month'', ``date'', and ``year'',
and output that as a date in the form ``August 13, 1984''.  Since
the date and year will be printed as numerical values, there's nothing
complicated about that, but how does \TeX\ convert the numerical value
stored under ``month'' into the name of a month?

That's what the \cmd{ifcase\bs month\bs or\bs January \dots} accomplishes.
The \cmd{ifcase} tells \TeX\ to look at the value of \cmd{month} and 
print the first argument if it's zero, the second argument if it's one,
the third if it's two, etc.  Thus, if \cmd{month} happens to have a value
of 5, \TeX\ would output the fifth argument, ``May''.  (The zeroth argument,
which comes before the first \cmd{or}, doesn't exist in this case because
there is no month zero.)  Thus, to get the date to be printed in the form
``13 AUG 1984'', we would write
\smallskip\noindent
\cmd{def\bs today\lb\bs number\bs day\bs ifcase\bs month\bs or JAN\bs or
FEB\bs or MAR \dots\ \bs or DEC\bs fi\bs number\bs year\rb}
\smallskip\noindent
(The \cmd{fi}
tells \TeX\ that there are no more cases to consider, so that if we happen
to be in month 13, we're in trouble!)

The next few lines control the overall appearance of the printed output.
They tell \TeX\ not to force each page to have exactly the same length
(\cmd{raggedbottom}), not to end a page in the middle of a paragraph
(\cmd{interline penalty=1000}), to make the width of the printed text
6.25 inches (``truein'' makes the page width independent of any \cmd{%
magnification} in effect), not to indent paragraphs, and not to put
extra space (controlled by \cmd{parskip}) between paragraphs.
These are things which are matters of individual taste and which someone
modifying the format for their own use might wish to change.

The \cmd{headline} command controls the appearance of a running
head across the top of each page of the letter:  if we're on the second
or subsequent page, \TeX\ will print a running head with the addressee's
name (following the word ``to''), the date, and the page number.
(``Folio'' is a macro defined by the plain \TeX\ format; in this case,
although not always,
it's essentially equal to the value of \cmd{pageno}.)  
\footnote{``Folio'' is a word used in typesetting to refer to a pagenunber.
A ``drop folio'' is a page number at the bottom rather than top of a page,
for example, on the first page of a chapter.}
If we're on
the first page, we don't want a header; this is accomplished by the
macro \cmd{ifnum\bs pageno$>$1 {\sl text of the header}\bs else\bs hfil%
\bs fi}, where the \cmd{hfil} tells \TeX\ to fill the header line with 
blank space if the page number is less than 2.

Most of the rest of the first page of the {\tt letterformat} file
consists of  macros which define the various commands we saw in the
input file, such as \cmd{address}, \cmd{body}, \cmd{closing}, and
\cmd{annotations}.  These are not of much interest, since they wouldn't
in general need to be modified in adapting this letterhead to your own
use.

However, the last 15 lines or so of the first page of the {\tt letterformat}
file contain the commands which actually print the Stanford letterhead,
return address, and date; these are worth examining more closely, since
they are what would have to be modified to make this into someone else's
letterhead.  First we have the definition of the command 
\cmd{nofatsletterhead}.  According to the definition, when executed,
\cmd{nofatsletterhead} defines \cmd{sendingaddress} and \cmd{returnaddress},
and then gives the command \cmd{letterhead}.  

\cmd{sendingaddress} is
what eventually will print the sender's name, title, and phone number on
the letterhead.  Notice the command \cmd{up}, which raises the square
brackets around the area code so that they are even with the numbers,
rather than slightly below them.
\cmd{returnaddress} is what will eventually print the return address on a
mailing label.   \cmd{returnaddress} consists of the sender's
name, and then instructs \TeX\ to execute the command \cmd{deptreturn}.
(We say that \cmd{returnaddress} ``calls'' \cmd{deptreturn}.)  
\cmd{deptreturn} consists of the name of the sender's department, and calls
\cmd{stanfordreturn}, which consists of the University's name and address.
Although we could have included the name, department, and University all
in a single macro, defining a series of commands this way makes the
macros easier to modify subsequently.

The command \cmd{letterhead}, when it is executed by \cmd{nofatsletterhead},
sets the page number to 1, next tells \TeX\ to execute the command
\cmd{univletterhead}, and finally prints the sending address and the date (as
defined previously) indented by the amount \cmd{longindentation} (equal
to 4 inches, according to a previous macro).  \cmd{univletterhead} 
is what prints the banner heading with the Stanford seal and name; it consists
of the complicated looking expression on the top of the second page which
only a true \TeX\ wizard would want to try changing.
\footnote{The Stanford seal is in a special printer font known as ``stan70''.
It was originally produced using a Xerox Graphic Printer in the Computer
Science Department, which scanned a photo of the seal and turned it into a
digital representation which could be stored as a font.  Don't you wish that
{\sl you} had all these funny machines!?!}

In order to customize this letterhead, then, we need only find the few
things which need changing to make this \cmd{yourletterhead} rather than
\cmd{nofatsletterhead}.  Presumably, these would consist of the contents
of \cmd{sendingaddress}, \cmd{returnaddress}, and \cmd{deptreturn}; everything
else would be fine the way it is (assuming, of course, that you happen to
work at Stanford!).

It's even possible to have more than one letterhead defined in the same
file.  For example, if Dr.~No Fats had two positions, as ``Professor
of Complicated Activities'' and ``Dean of Important Stuff'', he could
have a \cmd{deanletterhead} which defined \cmd{sendingaddress} as
{\tt DR. NO FATS\bs par Dean of Important Stuff\bs par Telephone}\dots,
and a \cmd{profletterhead} which defined it as
{\tt DR. NO FATS\bs par Professor of Complicated Activities
\bs par Telephone}\dots.  Each of these would have to call a separate  
\cmd{deptreturn}, of course.  Or, there could be a separate letterhead
for each faculty member in the Dept.\ of Reducing Medicine, each of
which defined \cmd{sendingaddress} and \cmd{returnaddress} differently,
but with the  \cmd{deptreturn} and everything else the same.

A single file can contain any number of macros.  However, in practice
\TeX's memory can fill up, so it's best to set up several different files
of macros for different purposes (business letters, technical papers, 
course outlines, etc.)  A macro file can also contain an \cmd{input}
command which causes \TeX\ to read in other files.


\section{More About Macros}

The way that \TeX\ deals with macros is quite simple: whenever \TeX\ sees
a macro command, it replaces  that command with the contents of its most
recent definition.  

Note the words ``most recent:'' each time a macro is
redefined, the new definition over-writes (``clobbers'') the old definition.
This is true unless the new definition occurs within a grouping, in which
case the new definition is {\sl local} to that grouping, and the old 
definition is automatically restored when the grouping ends.

Let's see some examples of how this works.  Suppose we have the following
set of macros:
\smallskip
{\tt\obeycr
\noindent \bs def\bs bar\lb B\rb
\bs def\bs foo\lb A\bs bar\rb
}
\smallskip\noindent
and we give the command \cmd{foo}; then \TeX\ will print ``AB''.
If we then say {\tt\obeycr
\bs def\bs bar\lb C\rb} 
and give the command \cmd{foo}, then \TeX\ will print ``AC'',
because the later definition of \cmd{bar} is what counts.  If we then said
\smallskip
{\tt\obeycr
\noindent \lb\bs def\bs foo\lb X\bs bar\rb
\bs foo\rb
\bs foo
}
\smallskip\noindent
then the first \cmd{foo} will print ``XC'', but the second will print
``AC'', because the redefinition of \cmd{foo} will be in effect only within
the brackets.  (If we  wanted to make the change to \cmd{foo} permanent,
we could have said \cmd{global\bs def\bs foo\lb X\bs bar\rb}.)

We can also have macros which, when executed, change the definition of other
macros (in fact, we've already seen this with the \cmd{nofatsletterhead}
macros).  Suppose we had the following: {\tt\obeycr
\bs def\bs foo\lb\bs def\bs bar\lb C\rb\rb
\bs def\bs bar\lb D\rb} 
and say \cmd{bar}; \TeX\ will print `D'.  However, if we say \cmd{foo}
and then say \cmd{bar} at any time thereafter, \TeX\ will print `C',
because executing \cmd{foo} redefines \cmd{bar}.

Because \TeX\ works with text substitution, there is nothing special about
the macros read in from an outside file; they can be changed by re-defining
them in your input file.  
\TeX\ will use the most recent definition of a macro regardless of where it
came from.
For example, if your input file read
\smallskip
{\tt\obeycr
\noindent\bs input letterformat
\bs def\bs today\lb August 12, 1984\rb
\bs nofatsletterhead
}
\smallskip\noindent
then the letterhead would print with a date of August 12 (no matter
what date it happened to be), since the input definition of \cmd{today}
in the input file will have clobbered the definition in the external
macro file.  However,  you must redefine \cmd{today} {\sl before} you
give the command \cmd{nofatsletterhead} in your input file, since changing
the definition of \cmd{today} after the date has been printed is not of
much use!

\section*{Assignment}

Reading for this lecture:  Read Appendix~E pages~403--408.

Assignment for this lecture: Copy the file {\tt sampleletter.tex} into
your directory by giving the command:
\smallskip
{\tt\obeycr
\noindent @copy texinputs:sampleletter.tex\ret
}
\smallskip
\noindent
Modify this file ({\tt sampleletter.tex}) to change the letter so that it
is signed by you instead of by Dr.~No Fats.

When you have tested that this works by running \TeX\ and printing the
output, copy the file {\tt letterformat.tex} into your directory:
\smallskip
{\tt\obeycr
\noindent @copy texinputs:letterformat.tex\ret
}
\smallskip
\noindent
Modify this file ({\tt letterformat.tex}) to change the letterhead format
so that it puts your name and computer address in the letterhead.
In addition, you should change the department name to Department of
Learning Typesetting.

Test this out by running \TeX.